Inside Macintosh: QuickDraw GX Objects /

Chapter 6 - Transform Objects / Transform Objects Reference

Functions / Manipulating Transform Object Properties

GXSetTransformTags

You can use the GXSetTransformTags function to add, remove, or replace tag objects associated with a transform object.

void GXSetTransformTags(gxTransform target, long tagType, 
                        long index, long oldCount, long newCount,
                        const gxTag items[]);

target

A reference to the transform object whose tag list you want to alter.

tagType

The type of tag objects to replace. A value of 0 indicates that you want to replace tags of all types.

index

The (1-based) index of the first tag reference (of the appropriate type) to replace.

oldCount

The number of tag references to replace. A value of 0 specifies that you want to insert tag references before the tag reference indicated by the index parameter, rather than replace tag references. A value of -1 (the gxSelectToEnd constant) indicates that all tag references of the requested type (starting with the reference indicated by the index parameter), should be replaced.

newCount

The number of tag references to insert. A value of 0 indicates that there are no tag references to insert; the existing tag references that match the selection criteria are removed from the target transform's tag list and disposed of.

items

An array of tag references to insert into the transform's tag list.

DESCRIPTION

The GXSetTransformTags function allows you add tag references to a transform object's tag list, to remove tag references from the list, or to replace tag references in the list with new tag references. In any of these three cases, the target parameter specifies the ink object to be modified, the newCount parameter specifies the number of tag references to add, and the items parameter provides the new tag references.

• To add tag references, set the oldCount parameter to 0. Use the tagType and the index parameters to specify where to add the new tag references. (For example, if you specify nil for the tagType parameter and 1 for the index parameter, this function inserts the new tag references before the current tag references. If you specify a value other than nil for the tagType parameter and a value of 2 for the index parameter, the function inserts the new tag references before the second tag reference with a tag type matching the tagType parameter.)
• To remove tag references, set the newCount parameter to 0 and the items parameter to nil. You can use the index and the oldCount parameters to specify which tag references (of the specified type) should be removed. The index parameter indicates the first tag reference (of the specified type) to remove and the oldCount parameter indicates how many tag references (of the specified type) to remove.
• To replace tag references, use the tagType, index, and oldCount parameters to indicate which tag references to replace, and use the newCount and items parameters to specify the new tag references to add. If newCount is greater than oldCount, the extra tag references are placed immediately adjacent to the last tag reference replaced.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
transform_is_nil
tag_is_nil
parameter_is_nil	(debugging version)
inconsistent_parameters	(debugging version)
parameter_out_of_range	(debugging version)
index_is_less_than_zero	(debugging version)
cannot_dispose_locked_tag	(debugging version)
Warnings
index_out_of_range
count_out_of_range
Notices (debugging version)
tag_already_set

SEE ALSO

Tag objects are discussed in the chapter "Tag Objects" in this book.

To examine the set of tags associated with a transform, use the GXGetTransformTags function, described in the previous section.